home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / tools / cie.txt < prev    next >
Text File  |  1993-07-24  |  9KB  |  197 lines
  1. C++ In Emacs (CIE) v 1.0
  2.  
  3. Archive-name: cie
  4. Environment: Emacs, C++
  5.  
  6. Author:  Brian M Kennedy (kennedy@intellection.com)
  7.          with contributions from:
  8.            Walt Buehring (tags.el and minibuffer-yank.el)
  9.            Sam Kendall (tags.el) 
  10.        (and, of course, the original tags.el author(s)).
  11.  
  12.  
  13. This package is a collection of some of the tools/enhancements we use for C++
  14. development work within GNU Emacs.  Briefly, it consists of an enhanced etags
  15. for C++, a related class hierarchy generator, a mode and M-x commands for
  16. browsing the hierarchy and getting lists of class members, a command goto-file
  17. that takes you to the proper line in a file, functions to make both tag names
  18. and file names mouseable, and a class manual generator that uses the hierarchy
  19. and tag information, coupled with the comments in the code, to build a class
  20. manual in texinfo format.
  21.  
  22. I've been stalling on releasing this, hoping to find time to implement some of
  23. the outstanding features and do some significant cleanup.  I have decided that
  24. I will never get to it (and I feel more and more guilty every time I see one
  25. of the many requests for these features on the newsgroups), so I am just going
  26. to release it basically as is.  My apologies.
  27.  
  28. Note the implication here -- in the past many, many months I have never found
  29. time to do any of the to-do queue.  You are welcome to send bug reports and
  30. suggestions, but it is highly improbable that I will ever manage to get to
  31. acting on them.  If you like this package, and want it to grow, consider 
  32. volunteering to adopt it and become its maintainer.  Any and all are welcome 
  33. to do so.
  34.  
  35. This has run with GNU Emacs 18.51, 18.55, 18.57 and 18.58.  I have not yet 
  36. switched to Emacs 19, so neither has this code.  If you want to use it with 
  37. Emacs 19, I encourage you to volunteer to "port" it for the rest of us ;-)
  38.  
  39. The etags++ and hier++ C++ programs have been compiled with Sun C++, 
  40. Centerline C++, Lucid C++, and Comeau C++ on Sun OS, Ultrix, and AIX 
  41. platforms.
  42.  
  43. =====
  44.  
  45. The directory etags++ contains source for two programs, etags++ and hier++.
  46. They are written in C++.  Assuming you have some reasonable C++ compiler
  47. accessible via command "CC", a simple make should build the two programs.
  48.  
  49. The file do-etags++ is simply an example of how to invoke etags++, hier++, 
  50. and emacs in batch mode to save out the tags-alist.  This is done for me
  51. automatically each night (but just takes a few minutes on 100K LOC).
  52.  
  53. The files cie.el and cie-mouse.el set up keystrokes and mousestrokes and
  54. autoloads for the other files.  You may want to load these (or variations)
  55. in your default.el or .emacs.
  56.  
  57. The other files (the meat) need to be dropped in your load-path somewhere.  
  58. Note that the tags.el should be loaded instead of (or after) the standard 
  59. tags.el.
  60.  
  61. The TAGS file generated by etags++ is standard format.  So, it is possible
  62. to use just that with the standard tags.el.  And this tags.el should work
  63. essentially the same as the standard tags.el on TAGS files generated by the
  64. standard etags program (that is important since etags++ only supports C/C++
  65. code; you must use the standard etags for Lisp, TeX, FORTRAN, etc.).
  66.  
  67.  
  68. Here are excerpts from the important files:
  69.  
  70. ======================
  71. ;;; tags.el
  72.  
  73. ;; INTELLECTION MODS:
  74. ;; 
  75. ;; 1) Prefers the tags named explicitly after C-A's at the end of each line.
  76. ;;    This is true both for find-tag and for the completion-alist.
  77. ;; 2) Support for C++ scoping -- class::name is considered a tag and both
  78. ;;    class::name and name are matches (class::name preferred though).
  79. ;; 3) Support for completion of scoped names as well as unscoped names.
  80. ;;    That is, the alist contains both the fully-scoped name, and each
  81. ;;    subname (c1::c2::mem => c1::c2::mem, c2::mem, and mem in the alist).
  82. ;; 4) Added mechanism to save out the completion alist into TAGS.alist
  83. ;;    which is checked for when loading TAGS to prevent the need to rebuild
  84. ;;    the alist (which can take a while with large systems).  As an added
  85. ;;    advantage, this mechanism removes duplicates from the alist before
  86. ;;    saving it out (making it faster and much smaller).
  87.  
  88. ======================
  89. ;;; hier-mode.el
  90. ;;; Hierarchy mode (for hierarchies output by hier++)
  91.  
  92. "Major mode for viewing class hierarchy files output by hier++.
  93. The file is formatted like this:
  94.  
  95. * class_a 
  96.   * child_b  :class_a
  97.   * child_c  :class_a :class_f
  98.     * grandchild_d  :child_c
  99.     * grandchild_e  :child_c
  100. * class_f
  101.   * child_c  :class_a :class_f
  102.     * grandchild_d  :child_c
  103.     * grandchild_e  :child_c
  104.   * child_g  :class_f
  105.  
  106. Classes child_b and child_c are derived from class_a; classes child_c and
  107. child_g are derived from class_f; classes grandchild_d and grandchild_e are
  108. both derived from child_c.  Note that each class (and all of its children) 
  109. will appear in the file once under each parent.
  110.  
  111. Defined keys:
  112. M-p moves to the previous sibling
  113. M-n moves to the next sibling
  114. M-u moves up to the parent
  115. M-h finds the first occurrence of the hierarchy element for a class 
  116.     (similar to M-. in behavior)
  117. M-g finds the next occurrence (like M-,) in the case of multiple-inheritance.
  118. M-m brings up a new window with a listing of all the members (both direct and 
  119.     inherited) of that hierarchy entry.  It does this via tags, so you must 
  120.     have tags set up in Emacs.  It will also only work properly if the tags 
  121.     file was generated by etags++ (companion to hier++)."
  122.  
  123. ======================
  124. ;;; class-manual.el
  125. ;;; Class Manual Generation
  126. ;;;   Code to use hier-mode (for hierarchies output by hier++) and etags++
  127. ;;;   functionality to build a class manual using the header comments in 
  128. ;;;   the code itself.  The formatting is in standard texinfo.
  129. ;;;   This is a hack that has been helpful for us, given our coding 
  130. ;;;   guidelines.  It will likely need modification to produce good
  131. ;;;   output for you.  (Header comments are those placed between the 
  132. ;;;   signature and the body of functions or classes.  If you don't follow
  133. ;;;   this convention, then this code will need modification.)
  134.  
  135. ======================
  136. ;;; goto-file.el
  137.  
  138. ;;; By binding goto-file to a key or mouse stroke, you can essentially
  139. ;;; make filenames "hot"; it will attempt to find that file in the 
  140. ;;; current buffer's default directory.  If no such file exists, then 
  141. ;;; it checks the current tags-table, gambling that it is one of your
  142. ;;; source files and will be tagged.
  143. ;;;
  144. ;;; Furthermore, it will try to go to the right location in the file.
  145. ;;; If there is an adjacent line number, then it will go to that line.
  146. ;;; Or if there is an adjacent grep pattern, then it will find that pattern.
  147. ;;;
  148. ;;; For instance, if you are in a shell and do an "ls", you can then click on
  149. ;;; any file name to open the file.  If you do a "make", you can click on any
  150. ;;; error msg to take you to the line of the error.  If you are in dbx, and it
  151. ;;; outputs a break or an assert outputs file/line, then you can simply click
  152. ;;; on the filename to take you to the line.  If you do a "grep", then you
  153. ;;; can simply click on the filename of the match that you want to go to.
  154. ;;; IMO, this is preferable to M-x compile or grep, because there is no need
  155. ;;; to proceed in order.  It also works everywhere: in source files, in
  156. ;;; shells, in night build logs, in mail buffers, etc.
  157.  
  158. ======================
  159. // etags++/c++file.c
  160. //
  161. // This .c file, written in C++, is intended to be included in etags++.c and hier++.c.
  162. // It is a quick-and-dirty "fuzzy" parser for C++ files that identifies enough tokens for
  163. // etags++ and hier++ to do a good job.  See those files for information on the resultant
  164. // functionality.  This file simply provides the common parsing code.
  165.  
  166. ======================
  167. // etags++/etags++.c
  168. //
  169. // This program reads in C++ code and generates a tags file for GNU Emacs.
  170. // This program is more sophisticated than the standard etags program for C++
  171. // programs.  It finds all classes, structs, unions, enums, enumerators, #defines,
  172. // typedefs, functions (both global and member), and data (both global and member).
  173. // Furthermore, it handles C++ scoping correctly, outputting fully-scoped tags
  174. // at the end of each line.  Thus, we have modified our Emacs tags.el to search
  175. // the fully-scoped names at the ends of the lines before the patterns.  It also
  176. // handles template syntax.
  177. //
  178. // In addition, we have added support for a few important macro conventions that
  179. // we use.  DECLARE_*(name,..) macros define the tag <name> in the current scope;
  180. // DEFINE_*(class,name,...) macros define the tag <class>::<name>.  We use NOTE(name)
  181. // macros to name comments, so that you can refer to them by See::name in other
  182. // comments.  In Emacs, M-. on See::name will take you to the named comment.
  183. //
  184. // Note that this uses "fuzzy", quick-and-dirty parsing to find the tokens.  Thus, it
  185. // can miss some things.  Also note that this is not an etags replacement -- it only
  186. // supports C/C++ code.  The etags program will still be needed for TeX, Fortran, etc.
  187.  
  188. ======================
  189. // etags++/hier++.c
  190. //
  191. // This program reads in C++ code and generates a "hier" file that displays the
  192. // class hierarchy.  You can then use the GNU Emacs hier-mode for traversing the
  193. // hierarchy and extracting information from your TAGS (if generated by etags++).
  194. //
  195. // Note that this program is built on the same quick-and-dirty "fuzzy" parser
  196. // that etags++ was, and will suffer the same ability to be fooled sometimes.
  197.